API to list console sessions #11016

bernardodemarco · 2025-06-12T15:37:30Z

Description

Currently, details about console sessions are stored in the cloud.console_session table in the database. Operators can only access this information by querying the database directly, while end users have no way to view console session data at all.

To address this, this PR proposes to create the listConsoleSessions API. It allows listing the console sessions, with optional filters by domain, account, user, host, instance, IP address, and date. The API is accessible to all account types and, thus, performs proper access validation on the queried resources.

The API supports the following parameters:

Parameter	Description	Required
`id`	Console session ID.	No
`activeonly`	Indicates whether only currently active console sessions should be listed. Defaults to `true`. Active sessions are the ones that have been acquired and have not been removed.	No
`acquired`	Indicates whether only acquired console sessions should be listed. Defaults to `false`. Acquired sessions are the ones that have been accessed. The `activeonly` parameter has precedence over the `acquired` parameter, i.e., when the `activeonly` parameter is `true`, the `acquired` parameter value will be ignored.	No
`isrecursive`	Lists console sessions recursively per domain. Defaults to `false`.	No
`clientaddress`	IP address of the client that accessed the console.	No
`consoleendpointcreatoraddress`	IP address of the client that generated the console session endpoint.	No
`hostid`	ID of the host where the VM was running when the console session endpoint was generated. Only available for Root Admins.	No
`virtualmachineid`	ID of the VM associated with the console session.	No
`startdate`	If provided, only console sessions that were generated from this date onward will be listed.	No
`enddate`	If provided, only console sessions that were generated up to this date will be listed.	No
`domainid`	Domain ID of the account that generated the console session endpoint.	No
`accountid`	ID of the account that generated the console session endpoint.	No
`userid`	ID of the user that generated the console session endpoint.	No
`page`	Used for pagination along with `pagesize`.	No
`pagesize`	User for pagination along with `page`.	No

This PR only encompasses the creation of the API listConsoleSessions API. UI support will be implemented in a future PR.

Types of changes

Breaking change (fix or feature that would cause existing functionality to change)
New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Enhancement (improves an existing feature and functionality)
Cleanup (Code refactoring and cleanup, that may add test cases)
build/CI
test (unit or integration test code)

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Major
Minor

Screenshots (if appropriate):

How Has This Been Tested?

Tests Setup

Created the following domain hierarchy:

ROOT
├── d1
│   └── d1-d1
└── d2

Created the following accounts:

Name	Role Type	Domain
admin	Admin	ROOT
u1	User	ROOT
d1-admin	DomainAdmin	ROOT/d1
d1-user	User	ROOT/d1
d1-d1-admin	DomainAdmin	ROOT/d1/d1-d1
d1-d1-user	User	ROOT/d1/d1-d1
d2-admin	DomainAdmin	ROOT/d2

Deployed a VM for each account:

ID	Name	Instance Name	Account Name
5	v-5-VM	v-5-VM	system
6	s-6-VM	s-6-VM	system
7	VM-fb5fa7ab-c5a0-4943-88bd-dedec9007c7b	i-7-7-VM	d1-d1-user
8	r-8-VM	r-8-VM	d1-d1-user
9	VM-16febbcd-a35e-4f05-87d3-1a27db077136	i-6-9-VM	d1-user
10	r-10-VM	r-10-VM	d1-user
11	VM-d3208889-d3fd-43fe-9087-3cf5d863a3b1	i-4-11-VM	d1-admin
12	r-12-VM	r-12-VM	d1-admin
13	VM-dea9f800-afd0-4054-9160-3a676a0df3d3	i-2-13-VM	admin
14	r-14-VM	r-14-VM	admin
15	VM-766b6485-330e-4ec9-9516-59e17b52c1c7	i-8-15-VM	u1
16	r-16-VM	r-16-VM	u1
17	VM-d2d7ded1-e210-4191-9a0e-75c3914de043	i-9-17-VM	d2-admin
18	r-18-VM	r-18-VM	d2-admin
19	VM-266b73ff-2684-46b9-b36e-830ac83c5c14	i-5-19-VM	d1-d1-admin
20	r-20-VM	r-20-VM	d1-d1-admin

With each account, I accessed all available VM consoles through the CPVM.

`listConsoleSessions` tests

With the admin account, verified that the API lists console sessions correctly according to the specified parameters
With the u1 account, verified that it is only possible to access the account's console sessions
With the d2-admin account, verified that it is only possible to list the console sessions of the d2 domain
With the d1-admin account, verified that it is only possible to list the console sessions of the d1 and d1/d1-d1 domains
With the d1-user account, verified that it is only possible to list the d1-user console sessions
With the d1-d1-admin account, verified that it is only possible to list the console sessions of the d1/d1-d1 domain
With the d1-d1-user account, verified that it is only possible to list the d1-d1-user console sessions
With accounts of the User type, verified that the hostid parameter is not considered in the API workflow
With accounts of the User type, verified that the hostid and hostname response attributes are not included in the API's return

bernardodemarco · 2025-06-12T15:38:23Z

@blueorangutan package

codecov · 2025-06-12T15:45:16Z

Codecov Report

❌ Patch coverage is 56.36943% with 137 lines in your changes missing coverage. Please review.
✅ Project coverage is 17.37%. Comparing base (a60c8ca) to head (dcece22).
⚠️ Report is 38 commits behind head on main.

Files with missing lines	Patch %	Lines
...loudstack/api/response/ConsoleSessionResponse.java	50.48%	51 Missing ⚠️
...n/java/com/cloud/vm/dao/ConsoleSessionDaoImpl.java	9.09%	40 Missing ⚠️
...mand/user/consoleproxy/ListConsoleSessionsCmd.java	50.81%	30 Missing ⚠️
...a/src/main/java/com/cloud/vm/ConsoleSessionVO.java	14.28%	6 Missing ⚠️
...udstack/consoleproxy/ConsoleAccessManagerImpl.java	87.50%	5 Missing and 1 partial ⚠️
...src/main/java/com/cloud/api/ApiResponseHelper.java	94.00%	1 Missing and 2 partials ⚠️
...in/java/com/cloud/server/ManagementServerImpl.java	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #11016      +/-   ##
============================================
+ Coverage     17.35%   17.37%   +0.02%     
- Complexity    15189    15222      +33     
============================================
  Files          5883     5885       +2     
  Lines        524514   524820     +306     
  Branches      64007    64026      +19     
============================================
+ Hits          91013    91196     +183     
- Misses       423216   423336     +120     
- Partials      10285    10288       +3

Flag	Coverage Δ
uitests	`3.63% <ø> (ø)`
unittests	`18.41% <56.36%> (+0.02%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

bernardodemarco · 2025-06-12T18:02:52Z

@blueorangutan package

blueorangutan · 2025-06-12T18:04:03Z

@bernardodemarco a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2025-06-12T19:05:38Z

Packaging result [SF]: ✖️ el8 ✖️ el9 ✖️ debian ✖️ suse15. SL-JID 13755

bernardodemarco · 2025-06-13T18:26:30Z

@blueorangutan package

blueorangutan · 2025-06-13T18:28:06Z

@bernardodemarco a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

DaanHoogland

clgtm, only doubt, is the active parameter needed? would we ever want to list no longer available sessions?

blueorangutan · 2025-06-13T18:54:26Z

Packaging result [SF]: ✖️ el8 ✖️ el9 ✖️ debian ✖️ suse15. SL-JID 13766

blueorangutan · 2025-06-13T19:37:33Z

Packaging result [SF]: ✖️ el8 ✖️ el9 ✖️ debian ✖️ suse15. SL-JID 13771

bernardodemarco · 2025-06-13T21:50:46Z

@DaanHoogland, thanks for the review!

is the active parameter needed? would we ever want to list no longer available sessions?

Yes, listing removed sessions is useful for audit and analysis purposes, as it allows users to track who generated a console endpoint, who accessed it, and when it was generated, acquired, and removed. Listing only active sessions, on the other hand, is helpful for verifying whether someone is currently using a VM.

blueorangutan · 2025-06-14T10:37:50Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ debian ✔️ suse15. SL-JID 13777

DaanHoogland · 2025-06-14T19:12:34Z

@blueorangutan test

blueorangutan · 2025-06-14T19:14:03Z

@DaanHoogland a [SL] Trillian-Jenkins test job (ol8 mgmt + kvm-ol8) has been kicked to run smoke tests

blueorangutan · 2025-06-15T11:19:33Z

[SF] Trillian test result (tid-13527)
Environment: kvm-ol8 (x2), Advanced Networking with Mgmt server ol8
Total time taken: 54933 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr11016-t13527-kvm-ol8.zip
Smoke tests completed. 141 look OK, 0 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File

DaanHoogland · 2025-06-16T07:12:15Z

@blueorangutan test ol8 vmware-70u3 keepEnv

blueorangutan · 2025-06-16T07:14:04Z

@DaanHoogland a [SL] Trillian-Jenkins test job (ol8 mgmt + vmware-70u3) has been kicked to run smoke tests

…leproxy/ListConsoleSessionsCmd.java Co-authored-by: Nicolas Vazquez <nicovazquez90@gmail.com>

…eAccessManagerImpl.java Co-authored-by: Nicolas Vazquez <nicovazquez90@gmail.com>

bernardodemarco · 2025-08-01T12:07:06Z

@blueorangutan package

bernardodemarco · 2025-08-01T12:07:21Z

@sureshanaparti, can we merge this one?

sureshanaparti · 2025-08-01T12:16:56Z

@blueorangutan package

sureshanaparti · 2025-08-01T12:17:36Z

@sureshanaparti, can we merge this one?

@bernardodemarco will check the build and merge

bernardodemarco · 2025-08-01T12:18:35Z

@sureshanaparti, can we merge this one?

@bernardodemarco will check the build and merge

Ok, thanks!

sureshanaparti · 2025-08-01T12:28:42Z

@blueorangutan package

blueorangutan · 2025-08-01T12:30:03Z

@sureshanaparti a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2025-08-01T14:12:41Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ debian ✔️ suse15. SL-JID 14506

sureshanaparti · 2025-08-01T14:57:58Z

Verified list consolesessions API call with latest build, looks good.

* create API to list console sessions

boring-cyborg bot added component:api component:management-server Python Warning... Python code Ahead! labels Jun 12, 2025

bernardodemarco added this to the 4.21.0 milestone Jun 12, 2025

bernardodemarco requested review from JoaoJandre, nvazquez, sureshanaparti, weizhouapache and winterhazel and removed request for weizhouapache June 12, 2025 15:37

bernardodemarco requested a review from DaanHoogland June 12, 2025 15:38

bernardodemarco force-pushed the listconsolesessions branch from 79f6d2d to ad7af57 Compare June 13, 2025 18:26

DaanHoogland reviewed Jun 13, 2025

View reviewed changes

bernardodemarco and others added 15 commits August 1, 2025 09:05

fix invalid access validation performed to the domainId attribute

5b87556

deal with inexistent provided domain ID

044d37b

add end of line to ListConsoleSessionsCmd.java

aebf9a9

enhance access control validation

a42decb

Update api/src/main/java/org/apache/cloudstack/api/command/user/conso…

b6d519d

…leproxy/ListConsoleSessionsCmd.java Co-authored-by: Nicolas Vazquez <nicovazquez90@gmail.com>

Update server/src/main/java/org/apache/cloudstack/consoleproxy/Consol…

a4531ad

…eAccessManagerImpl.java Co-authored-by: Nicolas Vazquez <nicovazquez90@gmail.com>

refactor createConsoleSessionResponse method

feab0c8

add instancename to the APIs response

c9424ff

add constants to ConsoleSessionDaoImpl

7f2ec61

check if consoleSession is null at the beginning of the method

b15254d

compare startdate and enddate parameters with the created attribute

896b465

add acquired param

5f15b87

rename instanceid param

b01e767

rename instanceid parameter

78a5f91

remove instanceid from api constants

dcece22

bernardodemarco force-pushed the listconsolesessions branch from cbd4295 to dcece22 Compare August 1, 2025 12:06

github-actions bot removed the status:has-conflicts label Aug 1, 2025

sureshanaparti merged commit 9de77e1 into apache:main Aug 1, 2025
24 of 26 checks passed

github-project-automation bot moved this from In Progress to Done in Apache CloudStack 4.21.0 Aug 1, 2025

dhslove pushed a commit to ablecloud-team/ablestack-cloud that referenced this pull request Aug 6, 2025

API to list console sessions (apache#11016)

456846f

* create API to list console sessions

sureshanaparti added the type:improvement label Aug 8, 2025

API to list console sessions #11016

API to list console sessions #11016

Uh oh!

Conversation

bernardodemarco commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Types of changes

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Screenshots (if appropriate):

How Has This Been Tested?

Tests Setup

listConsoleSessions tests

Uh oh!

bernardodemarco commented Jun 12, 2025

Uh oh!

codecov bot commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

bernardodemarco commented Jun 12, 2025

Uh oh!

blueorangutan commented Jun 12, 2025

Uh oh!

blueorangutan commented Jun 12, 2025

Uh oh!

bernardodemarco commented Jun 13, 2025

Uh oh!

blueorangutan commented Jun 13, 2025

Uh oh!

DaanHoogland left a comment

Choose a reason for hiding this comment

Uh oh!

blueorangutan commented Jun 13, 2025

Uh oh!

blueorangutan commented Jun 13, 2025

Uh oh!

bernardodemarco commented Jun 13, 2025

Uh oh!

blueorangutan commented Jun 14, 2025

Uh oh!

DaanHoogland commented Jun 14, 2025

Uh oh!

blueorangutan commented Jun 14, 2025

Uh oh!

blueorangutan commented Jun 15, 2025

Uh oh!

DaanHoogland commented Jun 16, 2025

Uh oh!

blueorangutan commented Jun 16, 2025

Uh oh!

bernardodemarco commented Aug 1, 2025

Uh oh!

bernardodemarco commented Aug 1, 2025

Uh oh!

sureshanaparti commented Aug 1, 2025

Uh oh!

sureshanaparti commented Aug 1, 2025

Uh oh!

bernardodemarco commented Aug 1, 2025

Uh oh!

sureshanaparti commented Aug 1, 2025

Uh oh!

blueorangutan commented Aug 1, 2025

Uh oh!

blueorangutan commented Aug 1, 2025

Uh oh!

sureshanaparti commented Aug 1, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

bernardodemarco commented Jun 12, 2025 •

edited

Loading

`listConsoleSessions` tests

codecov bot commented Jun 12, 2025 •

edited

Loading